The FilePack external package for 4D is simply a collection of File-Manager and related routines that NDG has used in one form or another for various contracts. When we purchased the 4D Externals Kit and discovered the new “package” format for bundling related functions & procedures into a single resource, it seemed like a great idea. I used the folder of source files for these file routines to test my understanding of the concepts out, and FilePack was born.
These are quick and dirty routines, thrown into the public domain for all to use free of charge in any way they see fit, but with the usual disclaimers: the software is offered “as is” for you to use at your own risk, with no expectation of support, bug-fixes or upgrades from me or NDG. We’ve not run the package thru any formal, documented testing procedure - they are tested as they are needed. This means _I_ am confident that they work, but you might not be.
While I am not making any promises or interested in hearing any complaints, I am always eager to hear suggestions, constructive criticism and bug reports. These routines are all written to work with both 2.0.11 and 2.1 (you will notice that many of the string parameters are typed as "TEXT" - this is why). I have NOT yet tested them with v2.1.1, but I have no reason to believe there will be any problems. Most are functions - I avoid passing values back from an external thru parameters because of the data-typing changes in v2.1 and because I hate having to create 4D globals just to call an external. As far as I can tell, you can directly pass any alpha, text or fixed-string expressions as parms to these routines.
Changes in v1.1:
1. GetFileName now accepts a "prompt" parameter, making it compatible with the other SFGet/Put routines, and requiring any code written with the old version to be rewritten (sorry!). You can rename the external using 4D External Mover or ResEdit, and then write a 4D global to handle the parm defaults, like this:
`GetFileName - Request a file selection
`I renamed the external GetFileName as NewGetFile
If(Count parameters=2)
$0:=NewGetFile($1;$2)
Else
$0:=NewGetFile("";$1) `Compatible with the old version
End if
2. Added two new SFGet-style routines: GetFoldername allows you to request a folder selection by the user, and GetVolumeName requests a volume. These routines use modified calls to the standard-file package, so they are (should be?) compatible with Boomerang, etc.
3. Added a new routine to allow you to load the directory of any folder into an array. With the addition of this routine, you can recreate DiskTools in 4D if you wanted to (IF you really wanted to...).
4. Renamed the GetVolName routine as GetDriveVolName, to clarify its function and the distinction with the new GetVolumeName routine.
5. Rewrote the GetVolSpace routine to accept the volume name instead of the drive number. If you depend on its functioning the way it did in v1.0, you can rename it using 4D External Mover or ResEdit, and then recreate it in 4D using code such as this:
`GetVolSpace - Determine the free space on a volume
`in a specific drive-no $1
`I renamed the external GetVolSpace as NewGetVolSpace
$volName:=GetDriveVolName($1)
If ($volName#"")
NewGetVolSpace($volName)
End if
6. Dropped the EjectDrive routine (which ejected a disk in the specified drive-number), in favor of the new EjectVolume routine (which ejects a named volume). If you depend on EjectDrive, you can recreate it in 4D using code such as this:
`EjectDrive - Eject the disk in a specific drive-no $1
Allows you to display the standard file package's "Open File" (SFGetFile) dialog, to allow the user of your application to select an existing file, optionally limiting the selectable files to those of specific types.
The first difference between this command and the native 4D command Open document is that this command does NOT open a channel to the selected file, in the event that you simply need the filename and do not wish to read/write to it immediately, need to perform any sort of validation or other processing, or wish to use the filename with any of the following FilePack routines that operate on existing files.
The other difference is that this command allows you to provide a prompt to your users right on the standard file dialog.
Parameters:
PromptString: String to be displayed immediately below the list of files and folders in the standard file dialog.
FileTypes: a string expression listing from 1 to 4 4-byte Macintosh file-type codes. Only files with one of the file type codes specified will be visible in the file dialog (and therefore selectable by the user). If a null string is passed, then all file types will be visible in the dialog.
Returns:
The fully-qualified name of the file selected by the user. If the user presses the dialog's Cancel button, returns a null string.
Examples:
vFileName := GetFilename("Select any file…";"")
vFileName := GetFilename("Select a text file…";"TEXT")
vFileName := GetFilename("Select a text or MacPaint file…";"TEXTMPNT")
PutFileName(prompt:T;defaultName:T):S
Description:
Allows you to display the standard file package's "Save File" (SFPutFile) dialog, to allow the user of your application to specify the name and folder for a new file, optionally allowing you to provide a prompt string and a suggested/default name for the new file.
The difference between this command and the native 4D command Create document is that this command does NOT create the new file and open a channel to it, in the event that you simply need the filename and do not wish to read/write to it immediately, need to perform any sort of validation or other processing, or wish to use the filename with any of the following FilePack routines that operate on new files.
Parameters:
PromptString: String to be displayed immediately above the text-edit field for the new file name in the standard file dialog.
DefaultName: String to be placed in the text-edit area for the new file-name, to act as a default or recommended name for the new file (the user will be able to replace this name with whatever legal name they prefer.
Returns:
The fully-qualified name of the file created by the user. If the user presses the dialog's Cancel button, will return a null string.
This function enables you to assign a new file-type and/or creator code for an existing file.
Parameters:
FileName: a string expression containing the fully-qualified file name.
TypeCode: a four-byte string containing the file-type code to be assigned to the file.
CreatorCode: a four-byte string containing the file-creator code to be assigned to the file.
Returns:
An error code indicating whether the file codes were assigned successfully. A non-zero result indicates that there was an error. See the File Manager chapter of Inside Mac for a listing and description of the possible errors.
Example:
vFileName := PutFilename("Export the worksheet info to…";"Today’s Export")
SetFileInfo(vFileName;"TEXT";"XCEL") `User can doubleclick right into Excel
GetFileCDate(fileName:T):D
Description:
This function enables you to determine the creation date of an existing file.
Parameters:
FileName: a string expression containing the fully-qualified file name.
Returns:
The date recorded by the Finder that the file was created.
Example:
vFileName := GetFilename("Select the Excel export";"TEXT")
If (GetFileCDate(vFileName) # Current date)
ALERT("I need to see today’s worksheet!")
Else
...
End if
GetFileCTime(fileName:T):L
Description:
This function enables you to determine the time of day that an existing file was created.
Parameters:
FileName: a string expression containing the fully-qualified file name.
Returns:
The time of day recorded by the Finder that the file was created. The time is returned as a LongInt representing the number of seconds since midnight.
Example:
vFileName := GetFilename("Select the Excel export";"TEXT")
Case of
:(GetFileCDate(vFileName)#Current date)
ALERT("I need to see today’s worksheet!")
:(GetFileCTime(vFileName)>43200))
ALERT("I need to see this morning’s worksheet!")
Else
...
End case
GetFileMDate(fileName:T):D
Description:
This function enables you to determine the date an existing file was most recently modified.
Parameters:
FileName: a string expression containing the fully-qualified file name.
Returns:
The date recorded by the Finder that the file was modified last.
GetFileMTime(fileName:T):L
Description:
This function enables you to determine the time of day that an existing file was last modifed.
Parameters:
FileName: a string expression containing the fully-qualified file name.
Returns:
The time of day recorded by the Finder that the file was last modified. The time is returned as a LongInt representing the number of seconds since midnight.
GetFileLogSize(fileName:T):L
Description:
This function returns the logical size of an existing file; i.e. the number of bytes that could actually be imported from the file.
Parameters:
FileName: a string expression containing the fully-qualified file name.
Returns:
The number of bytes of data in the file.
Example:
vFileName := GetFilename("Import which file?";"TEXT")
Case of
:(GetFileLogSize(vFileName)=0)
ALERT("This file is empty!")
:(GetFileLogSize(vFileName)>30000)
ALERT("This file is too big to store in a single field!")
Else
RECEIVE PACKET(…)
End case
GetFilePhySize(fileName:T):L
Description:
This function determines the physical size of an existing file; i.e. the number of bytes of space it occupies on disk.
Parameters:
FileName: a string expression containing the fully-qualified file name.
Returns:
The number of bytes of space occupied by the file on disk.
CopyFile(oldFileName:T;newFileName:T):I
Description:
This function allows you to make a copy of any existing file to any other folder on the same disk or any other mounted disk.
Parameters:
OldFileName: a string expression containing the fully-qualified name of the file to be copied.
NewFileName: a string expression containing the fully-qualified name of the copy of the file to be created. The complete pathname for the copy of the file to be created specifies which disk will hold the copy, the folder to put it in, and what its name should be. Therefore, this path must refer to a non-existent file in an existing directory; i.e. the volume name and folders specified must already exist, but the filename must not.
Returns:
An error code indicating whether or not the file copy was created successfully. A non-zero result indicates that there was an error. See the File Manager chapter of Inside Mac for a listing and description of the possible errors.
ALERT("There was a problem making the backup copy: "+String($result))
End if
NewFolder(pathSpec:T):I
Description:
Given a pathname of a non-existing folder whose parent path does exist (such as will be returned by PutFileName), creates the folder in the subdirectory of its parent.
Parameters:
NewFolderPath: the pathname of the new folder. The pathname must specify a new name in an existing directory.
Returns:
Zero if the folder was created successfully; if an error occurs, the OS error code will be returned. Usually, such errors will be caused by the specification of a name for a folder/file that already exists, or of a folder in a non-existent parent directory.
Example:
$folderName:=PutFileName("Create a Quick-Reports Folder…";"Reports")
if($folderName#"")
$result:=NewFolder($folderName)
If($result#0)
ALERT("There was a problem creating the new folder: "+String($result))
End if
End if
GetFolderName(prompt:T):S
Description:
Presents a modified SFGetFile dialog, allowing the user to select an existing folder, and returns the fully-qualified pathname for the selected folder. The dialog has an additional button called Select that will be enabled whenever a folder is highlighted in the file list area. The Select button allows the user to close the dialog and return the fully-qualified pathname of the highlighted folder to your procedure.
Parameters:
PromptString: String to be displayed immediately below the list of folders in the standard file dialog.
Returns:
The fully-qualified name of the folder selected by the user. The string will end with a semi-colon. If the user presses the dialog's Cancel button, returns a null string.
Example:
$folderName:=GetFolderName("Where are your Quick-Reports?")
if($folderName#"")
HFSCatToArray($folderName;asQRFiles)
End if
GetSystemPath:S
Description:
Returns the path name for the current system folder.
Parameters:
None
Returns:
The fully-qualified name of the folder containing the startup System file, Finder, etc. The string will end with a semi-colon.
Example:
$systemPath:=GetSystemPath
$prefFile:=$systemPath+"database.prefs"
GetDatabasePath:S
Description:
Returns the path specification for the current data file.
Note: This function uses the 4D callback routine EX_Get_Infos, and in order for this routine to function properly, you must force 4D to update the STR resource in your structure file by "manually" selecting the database file at least once.
Parameters:
None
Returns:
The fully-qualified name of the current database file.
Returns the path specification for the 4D structure file.
Parameters:
None
Returns:
The fully-qualified name of the currently-running structure or compiled-application file.
HFSParentName(pathSpec:T):S
Description:
This function returns the path name for the folder that a given file/folder is in; it simply strips away the file's simple name from its fully-qualified name.
Parameters:
PathSpec: a string expression containing the fully-qualified file/folder name.
Returns:
The path for the specified filename; i.e., all characters in the parameter value up to and including the last colon in the string.
Example:
vFileName := "Server:Databases:Export text"
vShortName := HFSParentName(vFileName)
`At this point, vShortName is equal to "Server:Databases:"
HFSShortName(pathSpec:T):S
Description:
This function returns the simple name for a given file/folder; it simply strips away the file's path name from its fully-qualified name. This performs the complimentary function to the HFSParentName routine.
Parameters:
PathSpec: a string expression containing the fully-qualified file/folder name.
Returns:
The simple name for the specified file/folder; i.e., all characters in the parameter value following the last colon in the string.
Example:
vFileName := "Server:Databases:Export text"
vShortName := HFSShortName(vFileName)
`At this point, vShortName is equal to "Export text"
HFSMove(oldPathSpec:T;newPathSpec:T):I
Description:
Given a pathname of an existing file or folder in the first parm, and the pathname to any other folder on the same volume in the second parm, will move the existing file or folder to the subdirectory of the other folder.
Parameters:
OldPathSpec: the pathname of an existing file or folder that you wish to move to a different location in the volume’s folder hierarchy.
NewPathSpec: the pathname of the folder that is to contain the existing file/folder after the move. This folder must be on the same volume as the file/folder to be moved.
Returns:
Zero if the move was completed successfully; if an error occurs, the OS error code will be returned. Refer to Inside Mac for a list and description of the possible error codes. Usually, errors are caused by specification of paths that do not exist or are not on the same volume.
Given the pathname for an existing file or folder, and a new simple name, renames the file or folder.
Parameters:
PathSpec: the pathname of an existing file or folder that you wish to rename.
NewName: a new simple name (do not respecify the entire path) for the file or folder.
Returns:
Zero if the file/folder was renamed successfully; if an error occurs, the OS error code will be returned. Usually, such errors will be caused by the specification of a non-existant file/folder for parm 1, or of an existing file name for parm 2.
Allows you to delete an existing file or folder (IF the folder is empty!).
Parameters:
PathSpec: the pathname of an existing file or folder that you wish to delete.
Returns:
Zero if the file/folder was deleted successfully; if an error occurs, the OS error code will be returned. Usually, such errors will be caused by the specification of a non-existant file/folder, or of a folder that is not empty.
Example:
$result:=HFSDelete("Server:Database:Really old file")
HFSExists(pathSpec:T):I
Description:
This function enables you to easily test for the existence of a file or folder.
Parameters:
PathSpec: a string expression containing the path to the file or folder to be tested.
Returns:
A value of 1 if the entry exists; zero if it does not.
Example:
If (HFSExists([Parms]HelpFileName))
vHelpFRef := Open document([Parms]HelpFileName)
...
Else
ALERT("Sorry, but something has apparently happened to the help file.")
End if
HFSCatToArray(pathSpec:T;arrayName:T)
Description:
Creates a text array containing a list of the simple names for all files and subdirectories contained in the specified folder. Folder names will end with a colon, while file names will not.
Parameters:
PathSpec: a string expression containing the path to the folder to be loaded.
ArrayName: a string expression containing the name of the text array to be created/replaced to store the folder's directory.
Note: if you are going to use this routine in a compiled database, you must be sure that you declare the array explicitly, using the ARRAY TEXT statement, somewhere in your application.
Returns:
Nothing - this is a procedure, not a function.
Example:
$folder:=GetFolderName("Folder to load?")
If($folder#"")
ARRAY TEXT(aCatList;0) `Predeclare for the compiler
HFSCatToArray($folder;"aCatList")
End if
EjectVolume(volumeName:T):I
Description:
Ejects the disk with the specified name.
Parameters:
VolumeName: Name of the volume to eject.
Returns:
Zero if the volume was successfully ejected; if an error occurred, a non-zero error code is returned. Usually such errors are caused by passing a name of a non-existant or non-ejectable volume.
Example:
$result:=EjectVolume("Backup Disk 1")
GetVolumeName(prompt:T):S
Description:
This function allows you to provide the user with a means of selecting a volume, and will return the selected volume's name. It displays a customized Standard-File dialog showing nothing but the Eject, Drive, Select and Cancel buttons, and a prompt that you supply.
Parameters:
Prompt: A string expression that will display along the bottom of the dialog.
Returns:
A string representing the name of the selected volume, or an empty string if the user cancels.
Example:
$volName:=GetVolumeName("Select a disk…")
GetDriveVolName(driveNo:I):S
Description:
Given a physical drive number (1-3 for floppies, >3 for hard disks, CD’s etc.), returns the volume name. Use this routine for identifying volumes in specific drives, or for generating a list of available volumes.
Parameters:
DriveNo: the drive number (potentially) containing a volume you wish to identify.
Returns:
A string representing the name of the volume in the designated drive, or a null string if the drive is non-existant or empty.
Example:
ARRAY STRING(32;aVolumes;7)
For($i;1;7)
aVolumes{$i}:=GetDriveVolName($i)
End for
GetVolSpace(volName:T):L
Description:
Given a volume name, returns the number of free bytes available on the disk.
Parameters:
VolName: a string representing the name of a mounted volume (such as that returned by GetVolumeName).
Returns:
The number of free bytes on the volume specified.
Example:
$diskSpace:=GetVolSpace("Server:")
IsVolLocked(volName:T):L
Description:
Enables you to determine if a volume is write-protected, i.e. if the user has set the sliding tab on the corner of the disk to the write-protected position.
NOTE: for some reason beyond me at the moment, this works fine with locked floppy-disks, but not with CD's... maybe soon I'll have time to figure out why (anybody out there have any suggestions?).
Parameters:
VolName: a string representing the name of a mounted volume (such as that returned by GetVolumeName).
Returns:
An integer value of zero if the disk is NOT locked, 1 if it is.
Example:
If(IsVolLocked($diskName)=1)
ALERT("Sorry, you can't export to that disk - it's locked!")
